.TH WFDBCOLLATE 1 "1 August 2002" "WFDB 10.2.7" "WFDB Applications Guide"
.SH NAME
wfdbcollate \- collate WFDB records into a multi-segment record
.SH SYNOPSIS
\fBwfdbcollate -i\fR \fIirec\fR [ \fIirec\fR ... ] \fB-o\fR \fIorec\fR
[ \fB-a\fR \fIannotator\fR ]
.br
\fBwfdbcollate\fR \fIorec first last\fR [ \fB-a\fR \fIannotator\fR ]
.br
\fBwfdbcollate -s\fR \fIirec \fR \fB-o\fR \fIorec\fR [ \fB-l\fR \fIsegment-length\fR ]
.SH DESCRIPTION
A multi-segment record is the concatenation of one or more ordinary
records.  A multi-segment record is a ``virtual'' record, in the sense
that it has no signal files of its own.  Its header file contains a
list of the records that comprise the multi-segment record.  A
multi-segment record may have associated annotation files, but these
are independent of any annotation files that may exist for its
constituent segments.  It is permissible (though not particularly
useful) to create a multi-segment record with only one segment; it is
not permissible to use a multi-segment record as a segment within a
multi-segment record, however.
.PP
\fBwfdbcollate\fR simply constructs an array of segment names, passing
it to the WFDB library function \fIsetmsheader\fR (see \fBwfdb\fR(3))
to create a multi-segment header file.  In the first form of the
command, \fIorec\fR is the name of the multi-segment (output) record
to be created, and the \fIirec\fR arguments are the names of the
(single-segment) input records that are to be included in the output
record.  At least one input record name must be specified.
.PP
In the second form of the command, \fIorec\fR is again the name of the
multi-segment (output) record to be created, and \fIfirst\fR and
\fIlast\fR are numbers between 1 and 99999.  In this case, \fIorec\fR
must be 3 characters or fewer (longer names are truncated), and the
names of the input records are derived by appending \fIfirst\fR,
\fIfirst\fR+1, ..., \fIlast\fR to \fIorec\fR (representing
\fIfirst\fR, ..., as 5-digit zero-padded decimal numbers).  Thus the
command
.br
	\fBwfdbcollate xyz 9 12\fR
.br
is equivalent to
.br
	\fBwfdbcollate -o xyz -i xyz00009 xyz00010 xyz00011 xyz00012\fR
.PP
Each segment must contain the same number of signals, and the sampling
frequency must be the same for each segment.  Each input record header
must specify its record length (use \fBwfdbdesc\fR(1) to determine the
input record length if necessary, then edit the input record header to
include this information before using \fBwfdbcollate\fR). In most cases
you will want to be sure that corresponding signals match in each
segment, and that the gains, ADC zero levels, and numbers of samples
per frame (see \fBheader\fR(5)) also match.  It is not necessary that
the signal file formats match, however.
.PP
In the first two forms, \fB-a\fR \fIannotator\fR is optional; if included, it
specifies the annotator name of annotation files associated with the
input records, files to be concatenated to form a similarly-named
annotation file for \fIorec\fR.  Note that all of the files to be
concatenated must have the same annotator name.  It is not necessary
that this annotator exist for each input record, however.
.PP
The third form of the command, which includes the \fB-s\fR option, can
be used to split an existing record (\fIirec\fR) into multiple
segments.  In this mode, \fBwfdbcollate\fR first creates a set of
segments from \fIirec\fR, then collates them into a multi-segment
record.  In this mode, the \fB-l\fR option may be used to specify a
non-standard segment length, which must be no less than 15 seconds.
By default, segments are 10 minutes long, although the last segment in
the record may be shorter.  The names of the segments created in this
way are formed from the first three characters of \fIorec\fR and from
a 5-digit zero-padded segment number, as in the second form of the
command.
.PP
In most cases, multi-segment records are indistinguishable from
single-segment records, from the point of view of applications built
using the WFDB library (version 9.1 or later).  Use \fBxform\fR(1) to
generate a single-segment record from a multi-segment record if
necessary (for example, to make it readable by an application built
using an earlier version of the WFDB library).  Note, however, that
older applications can generally be updated without source changes
simply by recompiling them and linking them with the current WFDB
library.
.SH ENVIRONMENT
.PP
It may be necessary to set and export the shell variable \fBWFDB\fR (see
\fBsetwfdb\fR(1)).
.SH FILES
.TP 22
\fIorec\fR.hea
output header file
.TP
\fIirec\fR.hea
input header file(s)
.SH BUGS
Under MS-DOS, this program is known as \fIwfdbcoll8\fR.
.SH SEE ALSO
\fBwfdbdesc\fR(1), \fBxform\fR(1), \fBwfdb\fR(3), \fBheader\fR(5)
.SH AUTHOR
George B. Moody (george@mit.edu)
.SH SOURCE
http://www.physionet.org/physiotools/wfdb/app/wfdbcollate.c
